<!--

    The contents of this file are subject to the license and copyright
    detailed in the LICENSE and NOTICE files at the root of the source
    tree and available online at

    http://www.dspace.org/license/

-->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!--
  Author:   Robert Tansley
  Version:  $Revision: 5844 $
  Date:     $Date: 2010-11-12 00:29:14 -0500 (Fri, 12 Nov 2010) $
-->
</head>
<body bgcolor="white">

Provides an API for accessing a relational database management system.
The main class is {@link org.dspace.storage.rdbms.DatabaseManager}, which
executes SQL queries and returns {@link org.dspace.storage.rdbms.TableRow}
or {@link org.dspace.storage.rdbms.TableRowIterator} objects.
The {@link org.dspace.storage.rdbms.InitializeDatabase} class is used to
load SQL into the RDBMS via JDBC.

<h2>Using the Database API</h2>

<p>
An example use of the Database API is shown below. Note that in most
cases, direct use of the Database API is discouraged; you should use
the <a href="../../content/package-summary.html">Content API</a>, which
encapsulates use of the database.</p>

<P>The <code>query</code> and <code>querySingle</code> have two sets of
parameters.  If you are merely reading data, and will not be changing any
values, you can use the forms without the <code>table</code> parameter.  This
allows you to perform queries with results pulled from multiple tables, for
example:</P>

<pre>
    TableRowIterator readOnlyRows = DatabaseManager.query(context,
    "SELECT handle.handle, item.submitter_id FROM handle, item WHERE
    handle.resource_id=item.item_id");
</pre>

<P>If you do wish to update the rows, you'll need to use the forms including the
<code>table</code> parameter, for example:</P>

<pre>
    TableRow updateable = DatabaseManager.querySingle(context,
        "item",
        "SELECT * FROM item WHERE item_id=1234");
    updateable.setColumn("submitter_id", 5678);
    DatabaseManager.update(context, updateable);
</pre>

<P>More example usage:</P>

<pre>
    // Create or obtain a context object
    Context context;

    try
    {
      // Run an arbitrary query
      // Each object returned by the iterator is a TableRow,
      // with values obtained from the results of the query
      TableRowIterator iterator = DatabaseManager.query(context,
      "community",
      "SELECT * FROM Community WHERE name LIKE 'T%'");

      // Find a single row, using an arbitrary query
      // If no rows are found, then null is returned.
      TableRow row = DatabaseManager.querySingle(context,
      "SELECT * FROM EPerson WHERE email = 'pbreton@mit.edu'");

      // Run an insert, update or delete SQL command
      // Returns the number of rows affected.
      int rowsAffected = DatabaseManager.updateQuery(context,
      "DELETE FROM EPersonGroup WHERE name LIKE 'collection_100_%'");

      // Find a row in a particular table
      // This will return the row in the eperson table with id 1, or null
      // if no such row exists
      TableRow epersonrow = DatabaseManager.find(context, "eperson", 1);

      // Create a new row, and assign a primary key
      TableRow newrow = DatabaseManager.create(context, "Collection");
      newrow.setColumn("name", "Test Collection for example code");
      newrow.setColumn("provenance_description", "Created via test program");
      // Save changes to the database
      DatabaseManager.update(context, newrow);
      // Delete the row
      DatabaseManager.delete(context, newrow);

      // Make sure all changes are committed
      context.complete();
    }
    catch (SQLException sqle)
    {
        // Handle database error
    }
</pre>
</p>

<h2>Database IDs</h2>

<p>
All tables in the DSpace system have a single primary key, which is an
integer. The primary key column is named for the table; for example,
the EPerson table has eperson_id.
</p>

<p>
Assigning database IDs is done by invoking the SQL function
<code>getnextid</code> with the table name as a single parameter.  The database
backend may implement this in any suitable way; it should be robust to access
via multiple simultaneous clients and transactions.</P>

</body>
</html>
